<html>
<head>
<title>Project 4 </title>
</head>
<body bgcolor="#ffffff">
<h1 align="center">Project 4 </h1>
<p>
<b>Due Date</b>:  Apr 15, by midnight.
</p>
<p>
[<b>Important Note</b>: If you are reading the <a href="./prj4.umt">./prj4.umt</a> version of this
document, please be aware of the fact that it is really the source code for
the <tt>HTML</tt> <a href="./prj4.html">./prj4.html</a> and <tt>PDF</tt> <a href="./prj4.pdf">./prj4.pdf</a> versions.  Hence it
contains markup; usually the markup is quite unobstrusive, but sometimes it
gets in the way.  In particular, some <tt>*</tt>'s and quotes may not make sense as
they are also used for markup.]
</p>
<p>
The document first describes the aims of this project.  It then gives the
requirements as explicitly as possible.  It describes the files which are
being provided and hints at how the project may be implemented.  Finally, it
lists exactly what needs to be submitted.
</p>
<h2>Aims</h2>
<p>
The aims of this project are as follows:
</p>
<ul>
<p><li>
To introduce you to using IPC using XSI shared memory.
</p>
<p><li>
To get you to synchronize independent processes using XSI semaphores.
</p>
</ul>
<h2>Requirements</h2>
<p>
Write a server program with executable <tt>quadrd</tt> and a client program
with executable <tt>quadrc</tt>.  The server program <tt>quadrd</tt> when invoked as
</p>
<pre>
   $ ./quadrd DIR
</pre>
<p>
should create a <b>iterative</b> server daemon running in directory <tt>DIR</tt>.  After
starting the daemon, the process started from the command-line should print
out the daemon's PID on standard output followed by a newline and exit.  The
started daemon should allow <tt>quadrc</tt> clients to evaluate integrals using
trapezoidal quadrature. The functions which are to be integrated will be
linked into the server executable at compile time from the file <tt>fns.c</tt> with
interface specified by <tt>fns.h</tt> as in <a href="../prj2/prj2.html">prj2</a>.
The server should support multiple concurrent clients but should contain
logic to ensure that concurrent quadrature requests from multiple clients
are effectively serialized.
</p>
<p>
The client program is invoked as:
</p>
<pre>
   $ ./quadrc DIR
</pre>
<p>
where <tt>DIR</tt> is the directory where the server is running.integration
</p>
<p>
The I/O behavior of the client should be identical to that specified in <a href="../prj1/prj1.html">prj1</a>.  After validating the input, the <tt>quadrc</tt> client should
send the input to the <tt>quadrd</tt> daemon using a agreed upon protocol and then
print out the result returned by the server on stdout as in prj1.
</p>
<p>
The details of the design of the communication protocol are left entirely to
you but must satisfy the following constraints:
</p>
<ul>
<p><li>
All IPC between clients and the server is to be performed using a
    single System V shared memory segment having a nominal size of 4KiB.
</p>
<p><li>
All synchronization is to be done using only System V semaphores.
</p>
<p><li>
Concurrent quadrature requests from multiple clients should be
    effectively serialized.
</p>
<p><li>
A client crash should usually not render the server inoperable.
</p>
</ul>
<p>
You may assume that a single quadrature request will fit within the shared
memory segment for any reasonable protocol.
</p>
<h2>Provided Files</h2>
<p>
The <a href="./files/">./files/</a> directory contains the following files:
</p>
<dl>
<p><dt><a href="./files/Makefile">Makefile</a><dd>
    This file can be used to build your project.  Assuming that all your
    client source code in <tt>quadrc.c</tt>, server source code is within a single
    file <tt>quadrd.c</tt>, <tt>fns.c</tt> having specification file <tt>fns.h</tt> contains the
    functions being integrated and definitions common to both client and
    server are in <tt>quadrdefs.h</tt>, then typing <tt>make</tt> will compile all your code
    and link into <tt>quadrc</tt> and <tt>quadrd</tt> executables.  You may modify the
    <tt>Makefile</tt> to meet the needs of your individual project.
</p>
<p><dt><a href="./files/quadrdefs.h">quadrdefs.h</a><dd>
    Common definitions shared between client and server.  Any additional
    definitions shared between client and server (like protocol parameters)
    may be added to this file.
</p>
<p><dt><a href="./files/fns.h">./files/fns.h</a><dd>
    The header file which specifies how the functions to be integrated
    are made available to the server program.
</p>
<p><dt><a href="./files/fns.c">./files/fns.c</a><dd>
    A sample file containing a couple of functions which can be integrated.
    This file should be linked with the server at compile time.
</p>
</dl>
<h2>Caution</h2>
<p>
<b>IMPORTANT</b>: In this project, you will be creating global IPC facilities.
Make sure you familiarize yourself with the <tt>ipcs</tt> and <tt>ipcrm</tt> commands and
use them to clean up facilities you no longer need.
</p>
<p>
As in your provious project, you will be creating multiple processes as well
as daemon processes.  It is important that you ensure that you do not create
runaway processes and that you clean up any garbage processes periodically
and definitely before you logout.  So use the same commands as you used in
<a href="../prj2/prj2.html">prj2</a> to ensure that you clean up.
</p>
<p>
Note that by definition, a daemon will survive your logging out, so it is
particularly important to specifically clean up your daemon processes.
</p>
<h2>Discussion</h2>
<p>
You will need to decide on the details of the communication protocol between
the <tt>quadrd</tt> server and <tt>quadrc</tt> clients.  These decisions involve multiple
aspects:
</p>
<ol type="1">
<p><li>
The details of the synchronization.  The synchronization should ensure
     that:
<ul>
<p><li>
Concurrent quadrature requests from multiple clients are
          effectively serialized.
</p>
<p><li>
The server should only read a client request from the shared
          memory after the client has completed writing the request to
          the shared memory.
</p>
<p><li>
A client should only read the server's response from the shared
          memory after the server has completed writing the response to
          the shared memory.
</p>
<p><li>
Attempt to ensure that the server outlives a client which crashes
          in the middle of a quadrature request.
</p>
</ul>
</p>
<p><li>
Given a decision on the synchronization, how will data be sent via the
     shared memory?  Text or binary?  Does it help to send the PID of the
     client to the server?
</p>
</ol>
<h2>Hints</h2>
<p>
The following steps are not prescriptive and may or may not make sense
depending on the details of your communication protocol between the server
and client:
</p>
<ol type="0">
<p><li>
Review the material on System V shared memory and semaphores.  Design
      the protocol for synchronization and communication between the client
      and server.
</p>
<p><li>
Start with a solution to <a href="../prj1/prj1.html">prj1</a> as a basis for
      your server.  Have a front-end which validates and then converts the
      lines from standard input specifying the quadrature requests to the
      data format needed for your communication protocol and writes each
      request into a buffer.  Setup the back-end code which does the
      quadrature to read the parameters from the buffer and write the
      quadrature results back to the buffer using the data format of your
      communication protocols.  For now, the synchronization between the
      front-end and back-end is merely via a synchronous function call where
      the front-end calls the back-end to read a quadrature request placed
      in the buffer, perform the quadrature and put the result back into
      the buffer.
</p>
<p><li>
Instead of using a normal memory buffer, make the buffer into a shared
      memory segment.
</p>
<p><li>
Split the front-end and back-end into separate programs.  The
      front-end will become the client program and the back-end the server
      program.  Make sure that you modify the client program to
      independently access the shared memory segment created in (2).
</p>
<p><li>
At this stage, you could test the operation of your client and server
      program by using flags in shared memory for synchronization along with
      busy waiting.
</p>
<p><li>
Setup the full synchronization in both server and client as per
      your protocol design.  Test.
</p>
<p><li>
Add code to make the server program into a daemon.
</p>
<p><li>
Iterate the previous steps until your program meets all the
      specifications.
</p>
</ol>
<h2>Submission</h2>
<p>
You should submit a archive <tt>prj4.tar.gz</tt> which contains all the source
files needed to build your project.
</p>
<ul>
<p><li>
The archive should not contain any executable or object files.
</p>
<p><li>
The provided <a href="./files/Makefile">Makefile</a> contains a <tt>submit</tt>
    target such that typing <tt>make submit</tt> will build the required
    <tt>prj4.tar.gz</tt> archive.  This presupposes that you have edited the
    <tt>Makefile</tt> to adjust it if you have a different organization for your
    source files than that outlined above.
</p>
<p><li>
The archive <b>must</b> contain a <tt>Makefile</tt> such that typing <tt>make</tt> in the
    directory containing the unpacked archive should build your project's
    main executable <tt>prj4</tt>.  You can test this before submission, by
    unpacking your archive into an empty directory and checking to see
    whether typing <tt>make</tt> builds correctly.
</p>
<p><li>
Your submission <b>must</b> include a <tt>README</tt> file which minimally contains
    at least your name and ID number.  It can optionally contain any
    comments you feel are relevant to the project like what works, what does
    not work, what you feel is neat, logs of test cases, etc.
</p>
<p><li>
Your submission should include any files from the <a href="./files">./files</a> directory
    your project uses, whether you modified them or not.  You will not need
    to modify the <tt>Makefile</tt> if you use exactly the same names and
    organization as that in the provided <a href="./files/Makefile">Makefile</a>.
</p>
<p><li>
You do not need to include any files used from the <tt>cs551s10</tt> library.
</p>
</ul>
<p>
The above archive should be email'd as an attachment to the TA at
<a href="mailto:ruiqi.luo@gmail.com">mailto:ruiqi.luo@gmail.com</a> with subject set to <tt>CS 451/551 Project 4</tt>.  If
you discover a mistake in your submitted project before the due date, you
may submit it again; only the latest submission will be graded.
</p>
</body>
</html>
